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INTRODUCTION 

TR (Tracing Routine) is a program to run other programs instruction 
by instruction. 

TR has control all the time (until control is passed to MAC) and exten- 
sive logging of the program execution may be obtained. 

In the TSS, TR can simulate the IOT instruction, which is illegal. In 
this way a program may be run in TSS without modifications if IOT 
instructions are used. 

Various protections are easily set and when violated, control is passed 
to MAC, and an error message is written out. 

TR may also be added as an option to MACF (MAC- File) and MACM 
(MAC Mass Storage Assembler). Thus TR executes programs on mass 
storage files. 
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PURPOSE 

The purpose of TR is to be a tool when debugging programs written 
in NORD-1 assembly language. 

Using TR increases efficiency in two ways: 

The user is provided with handy tools which enable him to 
pinpoint faults much quicker and with less effort. 

The log produced by TR may be examined after a run and 
therefore the need for computer-time is diminished. 
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GENERAL INFORMATION 



3.1 Program Information 

The trace routine must always operate together with the MAC assembler. 
It calls the routines INBT, OUTBT, ORT (floating point assembly) and 
OVER (disassembler) . TR can be placed anywhere in core. 

The TSS version of TR occupies about 3400 locations. The other version 
about 3300 o locations. 

o 

TR uses two addresses in MAC, the B-register and the entry point. All 
symbols used in TR have 9 as first character, 

3.2 Some Words of Warning to the User 

When TR executes a SMIL or JMP I (MAC instruction) , this will not cause 
control to be passed to MAC, but will continue tracing inside MAC if this 
is legal area (see Section 5.3) . If this is not legal area, ILL P or ILL 
JMP will be written out and control then passes to MAC. 

The routines INBT and OUTBT in the TSS version of MAC use monitor 
call (MCALL) . 

If a program which calls INBT and/or OUTBT is traced, the 9 lOT switch 
must be zero. This is because IOT SKA. n will just cause a skip if n is 
found in 9 DEVN (Section 6. 3) . If n is not found in 9 DEVN, an error- 
message will be written out (Section 8.3), 
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MINIMUM REQUIREMENTS TO TRACE A PROGRAM 

1 MAC with TRACE option is loaded. Note that this version of 
MAC should include the Disassembler option and Floating 
point assembly option as well. 

2 The program to be traced is assembled. 

3 Start address is set with command )9INN (Section 5. 3) . 

4 To start tracing type )9TR. Now TR should start printing the 
value of Current Location (CL) , T-, A- and X- registers. There- 
after these registers are printed only when they are charged. If 
no output occurs, check the trace area and rotation counter 
(Sections 5.2 and 5.3) if these are ok, something is wrong. Start 
again at point 1 or 2. 
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5 COMMUNICATION WITH TR 

5.1 Definitions 

Expression (denoted E) is an expression in MAC syntax. All symbols 
used must be defined. 

Tracepoint (TPO) is an address where all specified outputs are written 
out. 

On the TTY all the registers are specified with )9REG (see Section 5.3) , 
and on the line printer all registers are specified. 

The last point traced before control is passed to MAC is also regarded 
as tracepoint. 

5. 2 Syntax of Inpu t 

Commands without parameters are written just as in MAC: 

)9NN ? 
Commands to set the point tables 

)9NNN,_,[,/?/CR] E, E,E— v 

where E is the expression according to Section 5. 1. 

The comma will cause the values to be appended to the values already in 
the table. The ( ?) will cause the contents of the table to be listed out. 
The CR will cause the table to be reset. 

If none of these are specified, the table will be reset and filled from the 
beginning. 

Commands to set the area tables 

)9NNN^[,/?/CR] E<E,E<E— - ^ 

The lower limits must be less than the upper limits. Else analogous to 
the command above. 

Command to specify output 

) 9REG^ L , L , LLL , LLLL — > 

where L denotes letters, only the first letter after comma is significant. 
Spaces are ignored. 
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Commands to examine and set the contents of the registers. 

)9NVAL . , LA reply E 

) 9 OVAL , LLL/ reply E, 

Where L denotes letters, only the first letter after the space is signifi- 
cant. When the slash is encountered, the content of the specified register 
is printed on the Teletype. 

Description of the Commands 

)91NN Start point of tracing. 

Maximum 1 point. 
Initial setting: none. 

)9STOP Stop point. Run is aborted. 

The point also considered as a trace point. 
Maximum 12 points. 
Initial setting: none. 

)9TPO Trace point according to the definition 5.1. 

Maximum 12 points. 
Initial setting: none. 

)9PPO Printing points where the memory areas (see Section 5.3) 

are dumped. All the areas will be dumped. 
Maximum 12 points. 
Initial setting: none. 

)9LAR Legal areas, no action is allowed outside these areas. 

Maximum 6 areas. 
Initial setting: 77777 

)9TAR Tracing areas where the log is printed. The registers are 

only printed when changed if it is not a trace point. Old 
current location is only printed when CL-^OCL + 1. The 
first and last entry inside a trace area are regarded as 
trace points (even if it is not the start or end point of the 
area) . 

Maximum 6 areas. 
Initial setting: (K 77777 

)9BAR Blocked areas where it is illegal to store or change the 

contents of the memory. 
Maximum 6 areas. 
Initial setting: none. 
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)9MAR 



)9ROT 

)9LP 

)9RLP 
)9DS 



Memory dump areas which are dumped when a printing 
point is reached. 
Maximum (> areas. 
Initial setting: none. 

Takes two arguments. The first is the rotation counter (n) 

The second is the rotation address (A) . 

A will be passed n times before any printing is done. 

Selects the line printer as device for the trace output. 
Error messages will also appear on the Teletype. 

Resets output to Teletype. 

If this command is given, the current instruction and 
memory dump will be disassembled. The memory dump 
will be in both octal and symbolic code. It will also set 
the current instruction switch. 



)9RDS Resets disassembler and current instruction switch. 

Initial settings as if )9RD 
)9RLP was given, 

)9STEP Takes one argument if the argument is zero. TR will 

operate normal. If the argument: (n) is different from zero, 
n instructions will be run for each start. 
Initial setting: 0. 

)9IOT Takes one argument. Zero will cause the IOT SKA (nnn) 

instruction to be executed as a monitor call in TSS. 
Set to one, the IOT is simulated in the IOT SIMULATION 
routine (Chapter 6) . 
Initial setting: 0. 

)9FLT An argument different from zero will cause the T-A-D- 

registers to be printed as a floating point number. 
Initial setting: 0. 

)9TR Start tracing at the address. 

Set with) 91 NN 

)9CON Will continue tracing after an error stop or a stop address. 

)9PRIV Takes one argument. Privileged instructions may be treated 

in four different ways dependant on the argument value: 




1 
2 
3 



Execute 

Ignore 

Ignore, print message and continue 

Ignore, print message and stop 



Initial setting: 2. 
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)9REG Command to set the print switches, syntax according to 

Section 5. 2. 
The possible symbols are: 

CL - current location 

P - P- register 

T - T- register 

-A- - A -register 

" • I) -register 

X - X -register 

T ~ L -register 

B ~ ft -register 

STS - STS-register 

OCL - old current location 

REFADR - reference address 

I - current instruction 

Z - will reset the switch table when read 

(only the switches specified after "Z 1 ' 

will be set) . 

)9NVAL and ) 9 OVAL 

These commands enable the user to examine and change the contents of 
the new ()9NVAL) and old ()90VAL) registers (Chapter 7). 

Syntax according to Section 5.2. 

The possible symbols are listed above, however, OCL and Z have no 
meaning in this connection. 

The content of the specified register is printed on the Teletype. An 
expression terminated by carriage return will change the content of 
the register. Carriage return alone means no change. 
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THE IOT SIMULATION ROUTINE 

This routine is only used in TSS version of TR. It prepares execution 
of MCALL (see "Reference Manual for the ND Time-Sharing System", 
Chapter 6) or simulates IOT by means of INBT and OUTBT. 



6.1 



Monitor Call 



If the 9IOT switch is set to zero, IOT SKA will be executed as monitor 
call , It is illegal to specify higher monitor calls than 44. 



(i.2 



I O T 



If the 9IOT switch is set, IOT is simulated. IOT PIN and IOT SNI are 
illegal. 

SKA will always cause a skip. 



6.3 



Device Numbers 



The device number used in the IOT instruction must be found in the 
table 9DEVN 



9DEVN 



Initial setting i Corresponding file number 



3 

2 

7 

22 

67 



1 - TTY1 output 

1 - TTY1 input 

{ 3 - Tape punch 

j 2 - Tape reader 

| 5 - Iiine printer 



The device numbers in 9DEVN can be changed according to the device 
numbers used in each specific case. This may be done by putting the 
correct device numbers in the 9DEVN table by means of MAC. In 
MACF and MACM the device numbers in 9DEVN must be changed out- 
side the assembler, for instance from TSS or the OPR register. First 
examine the address of 9DEVN by using the colon command (:) in MAC. 

Example: 

A program is written for a system which uses 35 as device number. 
To run this program in TSS one would normally have to use a call 
ot OUTBT instead of writing IOT ACT SKA 35; JMP+ -1. 
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In TR the IOT instruction can be simulated if this device number 
is set in the table 9DEVN. If now 9DEVN + 2 /000007 35 is written, 
physical device number 35 is simulated by the equivalent logical 
device number 3. 

IOT ACT 35 will be equivalent to SAT> ,3; JPL I (OUTBT. In TR SKA 
will always cause skip. Therefore IOT ACT SKA 35; JMP* -1 is 
equivalent to SAT 3; JPL I (OUTBT. 
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THE INTERNAL REGISTERS 



The registers are held in two register blocks, one for new values 
and one for old values. 



7- 1 New Values 





CL 


- Current location 




P 


- P-register 




T 


- T-register 




A 


- A-register 




D 


- D-register 




X 


- X-register 




L 


- L -register 




B 


- B-register 




STS 


- STS-register 




R 


- Reference address (abs) 




I 


- Current instruction 


Old 


Values 






CL 


- Current location 




P 


- P-register 




T 


- T-register 




A 


- A-register 




D 


- D-register 




X 


- X-register 




I, 


- L- regis ter 




B 


- B-register 




STS 


- STS-register 




R 


- Reference address (abs) 



If the instruction is not a memory reference instruction, R will be zero. 

All these locations can be examined and changed if desired. 

In this way TR can be used similar to break point by setting stop points 
and using )9CON. 
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MESSAGES FROM TR 



Informative Messages 



STOP 



Stop address was reached 
Run was aborted. 



8.2 



Error Messages from Input Section 



TABL FULL 

UNDEF SYMBL 
L LIM ULIM 
FORMAT ERR 



Table overflow. The table was filled up and 
the access data were lost. 

Expression contained undefined symbol . 

Lower limit,. upper limit. 

Illegal character or syntax error in input. 



8.3 



Run Time Error Messages 



ILL INSTR 

ADR IN TR 
ILL J MP 

ILL LOAD 

ILL STORE 

BLOCKED STORE 

ILL MCALL 



Illegal instruction in TSS 
ION/IOF/INTDS/INTEN /MC L /MST/ 1 (i4 - - 
else only 164 , 

A location inside TR was referred. 

Attempt to jump outside. 
Legal area (Section 5. 3) . 

Attempt to load from location outside legal 
area (Section 5.3), 

Attempt to change a location outside legal 
area (Section r>, 3) . 

Attempt to change or store in a location inside 
a blocked area (Section 5.3) . 

The 9IOT switch was zero during IOT or 

MCALL higher thai? 44 was specified (Section 6. 1) , 
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ILL IOT OR DEVNO - IOT PIN/SNI was used or device number 

was found in DEVNO (Sections 6. 2 and 6. 3) . 

FATAL EUR - if this happens something is wrong with TR. 
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ASSEMBLING OF TR 

This section contains information for the system people only, and can 
be skipped by the user. 



9.1 



External Symbols 



The following symbols must be defined (only the first four if BRF output): 



LLS 

SOKS 

STOP9 

A 

FLAG 

ENTRY 

DGET 

OVER 

ORT 

INBT 

OUTBT 



In MAC 

In MAC 

In MAC 

In MAC 

In MAC 

In MAC 

Special for MACM or MACF 

In Disassembler option 

In Floating point assembly option 

In I/O system 

In I/O system 



9.2 



Conditional Assembly Symbols 



99 BRF 
99TSS 

MAC 

MACM 

MACF 



For BRF output 
For TSS versions 
For MAC versions 
For MACM versions 
For MACF versions 
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FLOWCHART FOR Tit 



Yes 
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Dump memo 



--.] Yes 



c' I (.elk' 
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SEND US YOUR COMMENTS!!! 



■*♦*»•**■**»*■**** 




Please let us know if you 

* find errors 

* cannot understand information 

* cannot find information 

* find needless information 

Do you think we could improve the manual by 
rearranging the contents? You could also tell 
us if you like the manual! 



Are you frustrated because of unclear information in 
this manual? Do you have trouble finding things? 
Why don't you join the Reader's Club and send us a 
note? You will receive a membership card — and 
an answer to your comments. 




*##********* 



HELP YOURSELF BY HELPING US!! 



*#***■*»**#** 



Manual name: Trace Routine 



Manual number: ND-60.046.02 



What problems do you have? (use extra pages if needed) 



Do you have suggestions for improving this manual ? 



Your name: 
Company: 
Address: . 



Date:- 



_Position:_ 



What are you using this manual for ? 



NOTE! Send to: 

This form is primarily for Norsk Data A.S ^ 

documentation errors. Software and Documentation Department 

system errors should be reported on P.O. Box 25, Bogerud Norsk Data's answer will be found 

Customer System Reports. 0621 Oslo 6, Norway on reverse side 



Answer from Norsk Data 



Answered by.„ 



_Date 



Norsk Data A.S 

Documentation Department 
P.O. Box 25, Bogerud 
0621 0slo6, Norway 



